10.3 Configuring MyID Desktop

10.3.1 Specifying the language for MyID Desktop

MyID Desktop uses the language setting of the client PC's Windows installation to determine the language to use.

Note: MyID differentiates between English (United States) and English (United Kingdom).

In the Windows Control Panel, under Clock and Region select the Change date, time or number formats option, then from the Format drop-down list select the language in which you want to display the user interface.

Note: It is possible to override this setting for the MyID workflows that are displayed using an embedded web browser control – make sure the setting in Internet Options > General tab > Languages matches the language set for Windows.

If you need to set the language to a different one from the language specified in Windows, contact customer support quoting reference SUP-138.

10.3.2 Communication between MyID Desktop and the MyID server

SIU references: SIU-248, SIU-249.

To allow your clients to communicate with the MyID server, your PC must be able to communicate with the URLs of the MyID web services; for example:

https://myserver/MyIDProcessDriver/

https://myserver/MyIDDataSource/

Where myserver is the name of the server on which the MyID web services are installed.

10.3.3 Server location

SIU reference: SIU-250.

MyID Desktop is configured to communicate with the MyID Web Services server when you install the MyID Desktop application. If you want to change the server, you can edit the configuration file.

Note: You must have the appropriate permissions to edit this file.

To edit the configuration file:

1. On the client PC, back up the MyIDDesktop.exe.config file in the following folder:

   C:\Program Files\Intercede\MyIDDesktop\

   On a 64-bit system, this is:

   C:\Program Files (x86)\Intercede\MyIDDesktop\

2. Using a text editor, open the MyIDDesktop.exe.config file.

   Note: Make the changes to the config file exactly as shown. The case is important.

3. Edit the value parameter in the following line:

   <add key="Server" value="http://myserver.example.com"></add>

   For example:

   <add key="Server" value="http://myserver2.example.com"></add>

   If you want to configure MyID Desktop to be able to connect to multiple servers (for example, if you have a test server and a production server) you can specify multiple servers.

   For example:

   <add key="Server" value="https://productionserver, https://testserver, https://testserver2"></add>

   By default, MyID Desktop connects to the first server in this list. If you want to connect to any of the other servers, you can specify the server address on the command line using the /server option; see section 10.4.1, Launching MyID Desktop with a specific server for details.

4. Save the configuration file.

The server URL must have the following format:

• Protocol – http:// or https://

  Note: Make sure you use the correct protocol: http or https. Use https if you have configured SSL/TLS.

• Server address – the address of the server. For example:

  myserver.example.com

For example:

https://myserver.example.com

10.3.4 One-way SSL/TLS

You must configure IIS to use SSL/TLS for your production environment. You can either use one-way (standard) SSL/TLS or two-way (client authenticated) SSL/TLS.

To configure MyID Desktop to use SSL/TLS for its communications with the MyID Web Services server, you must ensure that the client trusts the server SSL certificate. This requires that the issuing root CA is a trusted certificate, and that CRL/OCSP locations are accessible from the client for the entire certificate chain.

10.3.5 Two-way SSL/TLS

MyID Desktop supports two-way SSL/TLS.

10.3.5.1 Configuring MyID for 2-way SSL/TLS

There are incompatibility issues using MyID Desktop with SSL 2.0; however, SSL 2.0 is an old protocol and for security reasons should be disabled. If you do not disable SSL 2.0, you may experience errors when attempting to access certain workflows.

SSL has been superseded by TLS, which is supported by MyID Desktop. For more information on disabling old versions of SSL/TLS, see the System Security Checklist.

To set up the web server, you can use the Configure2WaySSL.ps1 PowerShell script; this is installed on the MyID web server in the Utilities folder.

The script takes the following optional parameters:

• webSiteName – This is the name of the web site that is hosting the MyID web service. By default, this is:

  Default Web Site

• installationPath – This is the folder where MyID was installed. By default, this is:

  C:\Program Files\Intercede\MyID

  If you do not specify this parameter, the script reads the installation folder from the registry.

• enable – If this is $true it will enable 2-way SSL/TLS; if it is $false it will disable 2-way SSL/TLS. The default is $true.

When enabled, the script ensures that Anonymous Authentication with the Require SSL and Require Client Certificate options is set for the MyID web sites and web services:

• MyIDDataSource
• MyIDProcessDriver
• MyID
• MyIDEnroll
• MyIDWebService
• upimages

The script will also turn off SSL for the images folder in MyIDDataSource, and GetImage.aspx and WindowsAuth.asmx in MyIDProcessDriver.

When disabled, the script turns off SSL/TLS for the MyID web sites and web services.

10.3.5.2 Setting up SSL/TLS on the client

Note: If your server is set up to use two-way SSL/TLS, you must set up your client to use two-way SSL/TLS. If you do not use the /ssl command-line option, an error is displayed.

Note: MyID Desktop does not support two-way SSL/TLS using a certificate stored on a smart card.

To use two-way SSL/TLS using a specific certificate:

1. Install the client certificate in the user's personal store.

   The client certificate must have the Client Authentication application policy – this has the following OID:

   1.3.6.1.5.5.7.3.2

2. Find the client certificate's serial number:

   1. Run the CertMgr.msc snap-in.
   2. Expand Personal > Certificates.
   3. Double-click the client certificate.
   4. Click the Details tab.

3. Run the application using the following command line:

   MyIDDesktop.exe /ssl /sslsn:<serial number>

   where:

   <serialnumber> – the serial number of the client certificate. Enter the serial number without spaces. For example, if the serial number is:

   62 00 00 00 34 fe 3c a9 a8 1c 98 6a f1 00 00 00 00 00 34

   use the following command line:

   MyIDDesktop.exe /ssl /sslsn:6200000034fe3ca9a81c986af1000000000034

Note: If you copy the serial number from the Details tab of the certificate properties dialog, you may inadvertently copy a non-printing character at the start of the serial number. You must make sure that you delete this character from the MyID Desktop command line. (Position the cursor before the : in the command line. Press the right-cursor key once. The cursor appears after the colon. Press the right-cursor key again. If the cursor does not move to after the first number in the serial number, there is a non-printing character present; press the Backspace key to delete it.)

If you run the application with the /ssl command line option but omit the /sslsn option, the application carries out the following:

1. The application checks the application settings file for the details of the last certificate that was successfully used to log on.
2. If no details are found, if the certificate is no longer in the personal store, or the server rejects the certificate, the application searches the personal store for certificates that match the issuer DN (optionally set up when you install the application) and have the Client Authentication policy.
3. If more than one certificate is found, the application displays a list of certificates for the user to select.

When the application has successfully logged on to the server using a certificate, the certificate's details are stored in the user's application settings file.

Note: When you start a legacy web-based workflow for the first time, MyID prompts you again for a certificate, and displays a list of the available certificates; this is because these workflows use an embedded browser. If you select the wrong certificate, you must restart MyID Desktop and try again.

10.3.5.3 Specifying two-way SSL in the configuration file

As an alternative to specifying /ssl and /sslsn on the command line each time you run MyID Desktop (for example, if you are launching MyID Desktop using a hyperlink, and therefore cannot specify /ssl or /sslsn) you can add settings to the <appSettings> node of the configuration file:

To edit the configuration file:

1. On the client PC, back up the MyIDDesktop.exe.config file in the following folder:

   C:\Program Files\Intercede\MyIDDesktop\

   On a 64-bit system, this is:

   C:\Program Files (x86)\Intercede\MyIDDesktop\

2. Using a text editor, open the MyIDDesktop.exe.config file.

   Note: Make the changes to the config file exactly as shown. The case is important.

3. In the <appSettings> node, add the following lines:

   <add key="TwoWaySSL" value="true"/>

   <add key="SSLCertificateSN" value="YourCertificateSerialNumber"/>

   If you want to stop using two-way SSL, you can set the TwoWaySSL value to false or remove the line. If you set this value to false, but include /ssl on the command line, the command line takes precedence, and MyID Desktop attempts to use SSL. If you specify a value for SSLCertificateSN but also include /sslsn on the command line, the command line takes precedence.

4. Save the configuration file.

10.3.5.4 Setting up client certificate hinting

If you have 2-way SSL/TLS set up, and start MyID with a smart card inserted, you may find that MyID is unresponsive until you remove the smart card from the reader. This is because more than one certificate meeting the client certificate requirements is available.

As a workaround, you can set up client certificate hinting on the MyID web server. This ensures that MyID looks for certificates from the correct certificate authority, and ignores the certificates issued to the smart card.

Note: This requires that your smart card certificates are issued from a different CA to your SSL/TLS client certificate.

To set up client certificate hinting:

1. On the MyID web server, run the Microsoft Management Console (mmc).

   Note: If you have multiple MyID web servers, you must carry out this procedure on each one.

2. Add the Certificates snapin for the Computer account.
3. Add the CA certificate that issued the client authentication certificate to the Client Authentication Issuers certificate store.

4. Set the following registry DWORD value to 1:

   HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\SendTrustedIssuerList

   If the registry key does not exist, you must create it.

5. Open a Windows command prompt as an administrator, and run the following command:

   netsh http show sslcert

6. Take a note of the ApplicationID and certhash it returns.

7. In the administrator command prompt, run the following commands, substituting in your own values for the ApplicationID and certhash:

   netsh http delete sslcert ipport=0.0.0.0:443
   
   netsh http add sslcert ipport=0.0.0.0:443 certhash=f27cc86a95570505dd5cffcbd670e65091f14620
   
   appid={4dc3e181-e14b-4a21-b022-59fc669b0914}
   
   sslctlstorename=ClientAuthIssuer clientcertnegotiation=enable

8. Restart IIS.
9. Ensure the website is set to require SSL and a client certificate.

10.3.6 Logging

You can set up your MyID Desktop application to write debug information to a log file. You may need to provide this information to Intercede customer support.

See the Windows clients section in the Configuring Logging guide for details.

10.3.7 Troubleshooting connection problems

If MyID Desktop fails to connect to the MyID server, a message similar to the following appears:

Unable to connect to the required MyID Web Service in a timely fashion
Possible reasons for this include:-
- Invalid application connection
- Server Expects a Secure Connection (SSL)
- Firewall blocking
- No internet / intranet connection
Because of the nature of this problem the application is unable to continue until the problem has been resolved.
Please contact your system administrator

If you experience any other errors, check the Error Code Reference document to see if it provides any suggestions to solve the connection problem.

If you cannot connect, try the following:

• Make sure MyID Desktop is configured for the appropriate MyID server.
• If your system is configured to use SSL, make sure that SSL is set up correctly. Make sure your SSL certificate is trusted.
• Make sure your firewall is not blocking HTTP or HTTPS communication between your client PC and the MyID web services server.
• Make sure you are connected to a network that has access to the MyID server.

If you see a message similar to the following:

Unable to access MyID
Unable to authenticate to MyID
Solutions:
Please contact your administrator

There may be a problem with the database configuration. On the MyID database server, open Microsoft SQL Server Management Studio, and check that the MyID COM+ user has the correct permissions. In particular, under Security > Logins, open the Properties for the MyID COM+ user, and check the User Mapping section. Make sure the user has public, db_datareader, and db_datawriter role memberships for the MyID database, and ensure that the Default Schema is set to dbo or another appropriate setting; a default schema of sys will cause connection problems.

10.3.8 Signature validation

MyID Desktop performs signature validation at startup to ensure that all components are properly signed by Intercede and have not been tampered with. These checks are performed using the native Windows APIs, and may require the client to connect to the Internet to retrieve the latest Certificate Revocation Lists (CRLs) for revocation checks of the Intercede signing certificate. If the client is permanently running in an isolated environment without access to the Internet, the CRLs cannot be retrieved, which can cause signature verification to fail. Under these circumstances, you may see an error similar to the following:

Failed to verify signature for running application. Error Code: 128

This error usually indicates that the client is unable to perform its revocation checks; to continue, you must disable these checks by adding an option to the application configuration file.

To edit the configuration file:

1. On the client PC, back up the MyIDDesktop.exe.config file in the following folder:

   C:\Program Files\Intercede\MyIDDesktop\

   On a 64-bit system, this is:

   C:\Program Files (x86)\Intercede\MyIDDesktop\

2. Using a text editor, open the MyIDDesktop.exe.config file.

   Note: Make the changes to the config file exactly as shown. The case is important.

3. Edit the value parameter in the following line:

   <add key="ComponentVerificationSkipRevocationChecks" value="TRUE"></add>

   If this line does not exist, you can add it to the <appSettings> section.

4. Save the configuration file.

When this option is enabled, the client performs all of its normal validation, but does not perform the revocation check. As the client does not need to retrieve the CRLs, it does not need to be connected to the Internet.

Note: This reduces the integrity of the signature validation, as the client will unable to determine if any of the certificates in the chain have been revoked since signing occurred – as such, you should ensure that the client's configuration file is modifiable only by users with administrative privileges.

10.3.8.1 Installing the required certificates for offline operation

If you have disabled the revocation check, you must also ensure that you have the appropriate certificates in the store of the client PC. On a PC with internet access, these certificates are obtained automatically; on a PC without internet access, you must obtain and install these manually.

To determine which certificates are required:

1. On a PC with internet access and MyID Desktop installed, locate the MyID Desktop program file in Windows Explorer.

   By default, this is:

   C:\Program Files (x86)\Intercede\MyIDDesktop\MyIDDesktop.exe

2. Right-click the file, and from the pop-up menu select Properties.

3. Click the Digital Signatures tab, then select the Intercede Ltd item in the Signature list and click Details.

   This is the code signing certificate.

4. Click View Certificate, then click Certification Path.

   • The certificate at the top is the root certificate – you must ensure that this certificate is in the trusted root store of the client PC. This is normally carried out by Windows Update, but a completely unpatched and disconnected PC may not have this certificate.
   • In the certificate chain, all certificates except the top and bottom certificates are intermediate certificates – you must ensure that these certificates are present in the intermediate certificate store on the client PC. These certificates are normally downloaded on demand, but may not be available on a disconnected PC.
5. Close the certificate dialog, then select the timestamp certificate in the Countersignatures list and click Details.
6. Obtain the root and intermediate certificates for this certificate, as you did for the code signing certificate.

10.3.9 Configuring timeouts

MyID Desktop is configured to time out after 30 seconds on some stages. This ends the current activity after that period of inactivity.

The default timeout for MyID Windows clients (MyID Desktop, the MyID Self-Service Kiosk, and the MyID Self-Service App) is controlled by the Page Timeout for Windows Clients configuration option (on the General page of the Operation Settings workflow).

If you want to change the timeout for a particular installation of MyID Desktop, you can edit the configuration file. This overrides the configuration option in Operation Settings.

To edit the configuration file:

1. Shut down MyID Desktop.

2. On the client PC, back up the MyIDDesktop.exe.config file in the following folder:

   C:\Program Files\Intercede\MyIDDesktop\

   On a 64-bit system, this is:

   C:\Program Files (x86)\Intercede\MyIDDesktop\

3. Using a text editor, open the MyIDDesktop.exe.config file.

   Note: Make the changes to the config file exactly as shown. The case is important.

4. Edit the value parameter in the following line:

   <add key="PageTimeoutSeconds" value="30"></add>

   If this line does not exist, you can add it to the <appSettings> section.

   For example:

   <add key="PageTimeoutSeconds" value="60"></add>

   This increases the timeout to 60 seconds.

5. Save the configuration file.
6. Restart MyID Desktop.